From: William Manley <will@williammanley.net>
Date: Fri, 22 Jun 2018 10:37:37 +0000 (+0100)
Subject: OstreeMutableTree: Document each private member of `OstreeMutableTree`
X-Git-Tag: archive/raspbian/2022.1-3+rpi1~1^2~4^2~21^2~41
X-Git-Url: https://dgit.raspbian.org/%22http:/www.example.com/cgi/%22https:/www.github.com/%22bookmarks:///%22http:/www.example.com/cgi/%22https:/www.github.com/%22bookmarks:/?a=commitdiff_plain;h=ca8571a49b1719887b06017a6c77798bb7f3bb6b;p=ostree.git

OstreeMutableTree: Document each private member of `OstreeMutableTree`

A prelude to my understanding.  Unfortunately `OstreeMutableTree` provides
little encapsulation, as each member has setters† so it's difficult to come
up with a list of invariants.

† `files` and `subdirs` only have getters, but the getters return mutable
  references to the internals, so we still can't reason about invariants.

Closes: #1645
Approved by: jlebon
---

diff --git a/src/libostree/ostree-mutable-tree.c b/src/libostree/ostree-mutable-tree.c
index 5cff5d82..f46e36db 100644
--- a/src/libostree/ostree-mutable-tree.c
+++ b/src/libostree/ostree-mutable-tree.c
@@ -47,10 +47,20 @@ struct OstreeMutableTree
 {
   GObject parent_instance;
 
+  /* This is the checksum of the Dirtree object that corresponds to the current
+   * contents of this directory.  contents_checksum can be NULL if the SHA was
+   * never calculated or contents of the mtree has been modified.  Even if
+   * contents_checksum is not NULL it may be out of date. */
   char *contents_checksum;
+
+  /* This is the checksum of the DirMeta object that holds the uid, gid, mode
+   * and xattrs of this directory.  This can be NULL. */
   char *metadata_checksum;
 
+  /* const char* filename -> const char* checksum */
   GHashTable *files;
+
+  /* const char* filename -> OstreeMutableTree* subtree */
   GHashTable *subdirs;
 };